Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Breaking Shape Contours

GXBreakShape

You can use the GXBreakShape function to break a single contour into two contours.

void GXBreakShape(gxShape target, long index);

target

A reference to the shape containing the contour to break.

index

The geometry index of the point at which to break the contour.

DESCRIPTION

The GXBreakShape function breaks an existing contour into two contours at a specified geometric point.

This function can convert the shape type of the target shape. For example, you can break line shapes at their first point by specifying a geometry index of 1 for the index parameter. The result is a polygon shape with two contours: the first contour is empty and the second contour is the original line. If you specify a value of 2 for the index parameter, this function posts the notice shape_already_broken, and the original line is unaffected.

Similarly, you can break curve shapes at their first point; the result is a path shape with two contours. You can also break curve shapes at the off-curve control point by specifying a value of 2 for the index parameter. The resulting path shape has two contours: the first contour ends at the off-curve control point, and the second contour begins at the off-curve control point. You must add on-curve geometric points at the end of the first contour and the beginning of the second contour before drawing this path shape.

The function affects polygon and path shapes in the following ways:

• If the geometry index you specify corresponds to the first point of a contour, this function inserts an empty contour into the shape before the specified point.
• If the geometry index you specify corresponds to the last point of a contour, this function posts a shape_already_broken notice, and the original shape is unaffected.
• If the geometric index you specify corresponds to a point between the first and last points of a contour, this function breaks the existing contour into two contours. The specified point becomes the first point of the new second contour.

For empty, full, and point shapes, this function posts the error graphic_type_does_not_contain_points. For rectangle shapes, this function posts a rectangles_cannot_be_inserted_into notice.

If you provide a target shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Posts the error graphic_type_does_not_contain_points
picture	Posts the error graphic_type_does_not_contain_points
text	Posts the error illegal_type_for_shape
glyph	Posts the error illegal_type_for_shape
layout	Posts the error illegal_type_for_shape

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
index_is_less_than_one	(debugging version)
shape_access_not_allowed	(debugging version)
rectangles_cannot_be_inserted_into	(debugging version)
graphic_type_does_not_contain_points	(debugging version)
illegal_type_for_shape	(debugging version)
Warnings
shape_access_not_allowed
index_out_of_range
contour_out_of_range
Notices (debugging version)
shape_already_broken

SEE ALSO

For an example using this function, see "Breaking Shape Contours" beginning on page 4-28.

For a discussion of geometric points, see Chapter 2, "Geometric Shapes," in this book. For other methods of breaking contours, see the shape-editing functions also described in that chapter.

To learn how this function works for the typographic shapes, see Inside Macintosh: QuickDraw GX Typography.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help